This file documents FWEB...

Copyright 1993 John A. Krommes

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to process this file through TeX and print the results, provided the printed document carries a copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual).

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled ``Copying'' is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.

FWEB
****

This info browser for FWEB is a ``work-in-progress''.  The previous large FWEB user manual (which was built in large measure from an early version of Levy's CWEB) is presently frozen at version 1.30. One can obtained a TeX'd copy of the present documention by saying tex fweb.texinfo.

The first part of this master menu lists the major nodes in this Info document.  The rest of the menu lists all the lower-level nodes in the document.

This Texinfo documentation describes FWEB Version 1.40, which initiates a major upgrade project.  This version contains significant improvements and new features, both visible and invisible to the user. THERE WILL BE BUGS.  If you are involved in a large programming project dependent on FWEB, it is not recommended that you upgrade this version unless you have a need for specific bug fixes.  Versions 1.4? are not intended for new users, but only for very patient friends.

FWEB Copying Permissions
************************

FWEB is "free"; this means that everyone is free to use them and free to redistribute them on a free basis.  FWEB operates under the terms of the GNU General Public License; see, for example, Distribution (The GNU Emacs Manual).

Although it is hoped that FWEB will be useful, there is ABSOLUTELY NO WARRANTY.

INTRODUCTION to FWEB
********************

FWEB is a system for ``literate programming''. It was originally intended for scientific programming, and is in wide use in that arena; however, it has much broader applicability.  It is an extension of Knuth's WEB system that handles the specific languages C, C++, Fortran, Ratfor, and TeX.  It also supports a WYSIWYG language-independent mode as well as a (closely-related but not identical) verbatim `language'.

The origins of literate programming are described in the very enjoyable book by D. E. Knuth, ``Literate Programming'' (Center for the Study of Language and Information, Leland Standard Junior University, 1992).

Knuth's original WEB was written in Pascal and formatted Pascal code. Silvio Levy introduced CWEB, a WEB system written in C for C.  FWEB is a (by now, substantial) modification of an early version of CWEB that was graciously supplied by Levy.  It also borrows various ideas from the work of Ramsey and Briggs on language-independent webs.

History of WEB and literate programming
=======================================

(To be completed; see Knuth's book.)

FWEB features
=============

FWEB is distinguished from its relatives in several respects:

  * FWEB introduces the concept of a current language (see Languages), so more than one compiler language can be processed in a single WEB run.

  * FWEB understands the syntaxes of several of the more important compiler languages:  C, C++, Fortran, Ratfor, and TeX.  For other languages, FWEB can work in a language-independent mode that essentially weaves and tangles the source code verbatim, but still provides the user with the powerful WEB features related to TEX documentation, module names, macro processing, etc.

  * FWEB contains a built-in Ratfor (RATional FORtran) translator. See Ratfor.

  * FWEB has a built-in C-like macro preprocessor, which should be especially useful for Fortran and Ratfor. See Macros, Preprocessing.

  * Many aspects of FWEB's behavior can be customized by means of setting parameters in a style file.

WEB CONCEPTS
************

The principle concepts of WEB programming are laid out in Knuth's book, the reference to which is given in Intro.  FWEB follows most conventions introduced by WEB and CWEB, except that the names of some commands have been changed for consistency, symmetry, and/or clarity.

The FWEB processors
===================

Following Knuth's original design, FWEB consists of two processors, FTANGLE and FWEAVE.  Both operate on a single source file, say test.web.  FTANGLE produces compilable code, say test.c, whereas FWEAVE produces a TeX file, test.tex, that can be processed with TeX or LaTeX.  For detailed descriptions of the LaTeX support, see LaTeX.

The structure of a web
======================

An FWEB source file is structured into sections. Each section consists of three (optional) parts: the

 1. TeX part;

 2. definition part; and

 3. code part.

Sections can be combined into larger units called modules, as explained in Modules.

A simple example of an FWEB source file consisting of two sections is as follows:

     @n

     @* INTRODUCTION.
     This code is intended...

     @m PI 3.14159

     @a
             program main
             call compute
             end

     @ The computational routine is pretty boring.
     @a
             subroutine compute
             write(*,*) 'pi = ', PI
             end

Commands to FWEB are begun by the @ symbol (see AT commands).  In this example, the first command, @n, sets the global language to Fortran-77.  For more information about languages, see Languages.

The @* command begins a major section (corresponding to LaTeX's \section command); this command is followed by the section name, terminated by a period.  Major sections are entered in the table of contents.  The command @*n begins a major (sub)section of level n, where @*0 is equivalent to the simple @*, @*1 indicates a subsection, @*2 indicates a subsubsection, and so on.

Minor sections are begun by @ ; these have no associated names and are not entered into the table of contents.

All sections begin with TeX commentary.  This is followed by an optional definition part.  The beginning of the definition part is signaled by the appearance of any one of the commands @d, @f, @m, @v, @W. In the example, the first section has a definition part consisting of one macro definition (@m); the second section has no definition part.

An unnamed code part is begun by @a.  A named code part is begun by the appearance of a module name such as @<Global variables@>, followed by an equals sign; see Modules.

The portion of the source file before the first section (i.e., before the first @* or @ ) is called `in limbo' or `the limbo part'.  The only @ commands that are allowed in limbo (in addition to @@, which is allowed anywhere) are the language-changing commands, and one of those should appear.  Other text in limbo is ignored by FTANGLE and is copied by FWEAVE to the output file.  Thus, one can make TeX macro definitions in limbo that override the defaults in FWEB's style file fwebmac.sty. (Another way of getting TeX text into the limbo part is by means of the @l command; see ATl.)

Modules
=======

Sections can be combined into modules. Modules can be named or unnamed. There is just one unnamed module.

The unnamed module
------------------

The unnamed module is introduced by the command @a.  Subsequent uses of @a accrete code to the unnamed module. FTANGLE outputs the unnamed module.

Named modules
-------------

A module name is specified by

     @< Arbitrary TeX text @>

Leading and trailing white space around the name text is ignored.

To define a named module, replace the @a that begins the unnamed code part of a section by @< module name @>=.  If one uses this construction with the same name in a later section, the effect is to accrete to the contents of the original section.  Thus, a named module might ultimately consists of the code from sections 2, 5, and 8, for example.

To use a named module, simply use the name anywhere in a code part; FTANGLE will insert the contents of the module at the point where the name is used.  For example,

     @c
     @ Here's how to use a named module.
     @a
     for(i=1; i<n; i++)
             @< Inner loop @>@;

     @ Here's how to define a named module.  Definitions may occur after use.
     @< Inner...@>=
     {
     a[i] = i;
     }

After a name has appeared once in full, it may be abbreviated by a unique prefix followed by 3 dots, as demonstrated in the above example. By convention, a complete module name cannot be a subset of another.  For example, @<Test@> and @<Test of graphics@> will elicit an error message.

Commonly the first unnamed section in the code indicates its modular structure.  For example, a C code might begin with

     @c
     @* DEMO.
     @a
     @<Include files@>@;
     @<Typedefs@>@;
     @<Function prototypes@>@;
     @<Global variables@>@;

This way, global variable definitions can be introduced as needed, but will be guaranteed to appear at the top of the code.  Function prototypes could be handled this way as well; alternatively, they could all be collected into one section, perhaps at the end of the source file.  (The above organization still guarantees that they will appear at the beginning of the output.)  Functions could be introduced one at a time in unnamed sections.

Phases of processing
====================

The FWEB processors perform their work in several distinct phases.

The phases of FTANGLE
---------------------

FTANGLE has two phases.  In phase 1, the source file is read; in phase 2, compilable code is written out in the order specified by the web.

More specifically, phase 1

  * discards TeX documentation;

  * tokenizes source;

  * expands @'...', @"...", and 0b... (in Fortran, also 0... and 0x...);

  * stores code text in appropriate modules;

  * memorizes macro definitions (@d and @m). See ATd, see ATm.

Phase 2

  * outputs outer macro definitions (@d);

  * outputs the unnamed module (@a);

  * expands WEB macros (@m);

  * expands built-in macros (see Built-in functions);

  * translates Ratfor statements.  See Ratfor

The phases of FWEAVE
--------------------

FWEAVE has three phases.  In phase 1, the source file is read and cross-reference information is collected.  In phase2, the source file is read again, then pretty-printed including the cross-reference information.  In phase 3, the index and table of contents are written.

More specifically, phase 1

  * tokenizes and stores identifiers and module names;

  * collects cross-reference information;

  * stores limbo text definitions (@l) (see ATl);

  * collects information about overloaded operators (@v) and identifiers (@W).  See ATv, ATW_.

Phase 2

  * outputs limbo text;

  * outputs special TeX macros for overloaded operators;

  * copies TeX material directly to output;

  * treats material between vertical bars (|...|) as code to be typeset;

  * tokenizes and stores contents of each code section;

  * analyzes code syntax and converts to appropriate TeX macros.

FILES
*****

FWEB works with a variety of files.  File names have the form [path]/root[.ext], where the brackets denote optional.  Here the slash is called the prefix end character.  Since this character differs for various operating systems, it can be changed in custom.h (see Customization). The character that initiates the file-name extension (normally a period) can be changed with the -E command-line option (see -E_).

Input files
===========

.fweb --- Initialization file; always in the home directory.

fweb.sty --- Style file; in the directory of the WEB file unless changed by environment variable FWEB_STYLE_DIR.  The basic name can be changed by the -z option (see -z).

name.web --- Source code.

name.ch --- Change file.  See Change files.

name.hweb --- Code included into web file with @i (see ATi). Include files are searched for in the path set by the environment variable FWEB_INCLUDES and/or the -I option (see -I_). If that path is empty, then the current directory is searched.

name.hch --- Change file for include file.

Automatic file-name completion
------------------------------

Automatic completion of input file names is turned on by the -e command-line option (see -e). When in effect, input file names that include no period (have no extension) are completed automatically according to the contents of the following style-file entries:

     Type of file    Style-file entry      Default

     WEB file           ext.web          .web
     Change file        ext.ch           .ch
     Include file       ext.hweb         .hweb
     Change file
      for include file  ext.hch          .hch

More than one extension may be specified, as a space-delimited list---e.g., "web wb"; the first one that matches is used.

Output files
============

name.tex --- Woven output to be processed with TeX or LaTeX.

CONTENTS.tex --- Temporary file that accumulates table-of-contents information.

INDEX.tex --- Temporary file that stores indexing information.

MODULES.tex --- Temporary files that stores module list.

name.ext --- Compilable output file.

The names of the three temporary files can be changed with style-file options.  See Style. Commonly, one may put into the style file fweb.sty commands such as

     index.tex "#.ndx"
     modules.tex "#.mds"
     contents.tex "#.cdts"

The # is replaced by the root name of the web file.

The extensions for the compilable output file(s) have certain defaults, but can be changed by style-file parameters according to the following table:

     Language        Style-file entry    UNIX default   non-UNIX default

      C               suffix.C               .c              .c
      C++             suffix.Cpp             .c++            .cpp
      Fortran--77     suffix.N               .f              .for
      Fortran--90     suffix.N90             .f              .for
      Ratfor--77      suffix.R               .f              .for
      Ratfor--90      suffix.R90             .f              .for
      TeX             suffix.X               .sty            .sty
      VERBATIM        suffix.V               .mk             .mk

Change files
============

The primary input to the FWEB processors is the test.web source. However, a change file test.ch can also be specified.  A change file consists of instances of the following structure:

     @x
     (One or more lines of text, EXACTLY as in the web file.  Copy these
     lines with the editor; don't type them from scratch.)
     @y
     (Replacement text.)
     @z

The change-file mechanism allows one to insert local changes or test new code without physically modifying the original web file.

To specify a change file, use its name as the second file name on the command line.  The extension .ch is assumed by default.  For example,

     FTANGLE test test

processes test.web with the change file test.ch.

In addition to @x, @y, and @z, the only @ commands allowed in a change file are language-changing commands such as @c and the special commands @[ and @].  The command @[ is used for column-oriented languages such as Fortran--77 and means switch into code mode.  Similarly, @] means switch out of code mode.

All @ commands in a change file must begin in column 1.  Lines not beginning with @ are ignored, so may be used as comments.

RUNNING FWEB
************

FWEB has a Unix-style command-line syntax.  There are many command-line options, but most of these are unnecessary for standard appplications.

Commonly-used command-line options can be placed into the initialization file .fweb. See Options.

Command-line syntax
===================

The command-line syntax is

     ftangle-|
             | webfile[.web] [changefile[.ch]] [-option...]
     fweave--|

File names are anything that doesn't begin with a -.  Options begin with a -.  File names and options can be intermixed, or the options may appear before the file names.  The first file name encountered is the web file (source file); the second, if it exists, is the change file.  [When no change file is specified, FWEB attempts to read from the null file (/dev/null on Unix systems).  This name should be specified when FWEB is installed, or can be set in the style file.  See null_file.]

An option consisting of a lone hyphen stands for the special file name stdin, which means `read from the standard input.'  (This option should not be used except for very special effects.)

The web file is shown as required since one is normally processing a source.  However, a few of the information options (see Info options) will work even in the absence of a web file.

Command-line options
====================

Command-line options may be put into the initialization file .fweb (which is always in the user's home directory). In that file, options beginning with a plus sign are processed before the command-line options.  Otherwise, they are processed after the command-line options.

Negating options
----------------

To negate a command-line option, use an extra hyphen.  For example, --v means `Don't make all comments verbatim.'  This kind of construction is useful if an option such as  -v is turned on in the .fweb initialization file and you wish to turn it off for just one run.

-1: Turn on brief debugging mode (FWEAVE).
------------------------------------------

This option tells FWEAVE to display irreducible scraps.  (Need discussion somewhere of scraps.)

-2: Turn on verbose debugging mode (FWEAVE).
--------------------------------------------

This commands tells FWEAVE to display detailed reductions of the scraps as it does the pretty-printing.  Sometimes FWEAVE fails spectacularly at printing-printing a section, either because of a syntax error on the part of the user or because of a bug in FWEAVE's logic.  This option helps one to figure out why.

This feature can be turned on more locally by means of the @2 command.  See AT2.

-@: Display the control-code mappings.
--------------------------------------

This command supplies information about the @ control codes:  it shows the associated style-file parameters that can be used to remap the codes, and it displays the precedence.  (Some codes may be used anywhere; others begin  a new part.  Codes that begin the definition part are labelled by [D]; codes that begin the code part are labelled by [C]; codes that begin a new section are labelled by [S].)

-A_: Turn on ASCII translations.
--------------------------------

This command is used primarily for debugging.  FWEB works internally with the ASCII character set.  If FWEB is run on a non-ASCII machine, translations to and from the internal ASCII are done automatically; on an ASCII machine, these translations are unnecessary and are not performed unless the -A option is used.

-B: Turn off audible beeps.
---------------------------

FWEB sometimes beeps the terminal for certain errors.  The -B option turns off the beeps, replacing them by a printed exclamation point.

(This option is sometimes called the ``marriage-saver'', after the situation that prompted a user's request for this feature.)

-b: Number blocks.
------------------

Number do and if blocks in woven Fortran and Ratfor output.

-c: Set global language to C.
-----------------------------

See Languages, C.

-c++: Set global language to C++.
---------------------------------

See Languages, Cpp.

-D: Display reserved words.
---------------------------

This option displays the list of reserved words for the language currently in force.  Thus, to see the reserved words for Ratfor--90, say

     ftangle -Lr9 -D

For this option one must set the language on the command line, because the -D option is processed before the limbo section of the web file is read.)

If you say -Dabc, you will get just the reserved words that begin with "abc".

-d: Convert do...enddo.
-----------------------

Obsolete.

-E: Change the delimiter of a file-name extension.
--------------------------------------------------

The standard delimiter for file-name extensions is a period, as in test.web.  To change this character to a comma, for example, say -E,.

-e: Turn on automatic file-name completion.
-------------------------------------------

When the -e option is in effect, FWEB attempts to be helpful in figuring out what file name you intend.  For any input file name that has no extension (no embedded period), FWEB completes the name by adding the extension contained in the style-file parameter listed in the following table:

             Type of file    Style-file entry      Default

             WEB file           ext.web          .web
             Change file        ext.ch           .ch
             Include file       ext.hweb         .hweb
             Change file
              for include file  ext.hch          .hch

More than one extension may be specified, as a space-delimited list---e.g., "web wb"; the first one that matches is used.

-F: Compare output files with old versions.
-------------------------------------------

When the -F option is in effect, FTANGLE writes its output to a temporary file (or files) instead of to its ultimate destination---e.g., test.c and/or test.f.  After all output is written, the temporary files are compared with the old version of the files, if they exist.  If the files are identical, the appropriate temporary file is deleted; otherwise, the temporary file is renamed, effectively overwriting the old version.  This feature avoids updating the time stamp on the file unnecessarily, so make files won't recompile the output unless it really has to.

(Note that with this option in effect, if one used the Unix utility touch to force processing of a group of files, but the WEB sources are never changed, the make file will continue to tangle the sources no matter how many times it is run, since FTANGLE will never update the time stamp on the files.)

The location of the temporary file as well as details of the renaming procedure are determined by the automatic configuration script during installation of the processors.  The script ./configure first looks for the (non-ANSI) function tempnam. If it finds it, it uses it to place the temporary file in the directory that FWEB would normally use for output in the absence of the -F option.  (That is usually the current directory.)  If tempnam is not available, the ANSI routine tmpnam is used. That places the temporary file in a directory determined by the system.

To implement the renaming, the rename function is used.  This may fail if tmpnam placed the temporary file on a different device.  If so, an attempt is made to force the rename by using the |system| routine to issue a mv command.  Terminal output indicates the progress of the renaming.  An asterisk following an output file name indicates that rename did not succeed, but the mv command did.

-f: Turn off module references for identifiers.
-----------------------------------------------

By default, FWEAVE gives certain entities such as function names a section-number subscript to indicate where that function was defined. The -f command turns off the subscripting operation.

The subscript operations are further controlled by the settings of the style-file parameters mark_defined.  See S_mark_defined.

-h: Get help.
-------------

This just prints a message saying where further help is available.

-I: Append to search list for include files.
--------------------------------------------

The fundamental search list for include files is defined by the environment variable FWEB_INCLUDES, which is a colon-delimited list such as

     setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff

The -I option appends to this list.

-i: Don't print @I include files.
---------------------------------

If a web file is included via @I (see ATI_), for example

     @I formats.hweb

then the -i option means to read and process the web file, but don't print its contents.  This option is often used for large files of macro definitions, formats, or typedef statements that must be included at the beginning of even very short web files; it clutters things up to print such header files all the time.

Note that files included via @i do not respond to -i or -i!.

-i!: Don't read @I include files.
---------------------------------

If a web file is included via @I, for example

     @I formats.hweb

then the -i! option means to ignore such files completely.  This option is seldom useful; the -i option (see -i) is more often used.

-L: Select global language.
---------------------------

To select a global language from the command line, say -Ll, where l is one of {c,c++,n,n9,r,r9,x}.  See Languages.

-l: Echo input line.
--------------------

The option -l[mmm[:nnn]] echoes the input line constructed by the input driver between lines mmm and nnn.  Missing nnn means echo to the end of file.  Missing mmm means echo from the beginning.

This option is useful as a debugging tool.  It is often used to verify that the input driver is inserting semicolons correctly.  For Fortran--77, it is also useful to verify that comments are being processed correctly.

-m: Define WEB macro.
---------------------

The command-line construction

     -mA(x)=x

defines the WEB macro A as though the definition

     @m A(x) x

had appeared at the beginning of the web file.

-m4: Understand m4 built-in commands.
-------------------------------------

This tells FWEAVE to properly format the reserved words of the m4 preprocessor.  The use of this preprocessor is not recommended; use FWEB's built-in preprocessor instead.

-m;: Append pseudo-semicolons.
------------------------------

When -m; is in effect, the construction @; is appended automatically to all WEB macro definitions.

This option is not recommended.  Insert the @; by hand when necessary, as in

     @m SET(x,y) x=1; y=2@;

-n: Set global language to Fortran--77.
---------------------------------------

See Languages, Fortran.

-n9: Set global language to Fortran--90.
----------------------------------------

See Languages, Fortran.

-n;: Supply automatic semicolons (Fortran).
-------------------------------------------

This is the default mode of operation in Fortran--77; the input driver automatically appends a semicolon to each logical line of source code. Since it's the default, you don't have to use it unless you wish to negate it.  See Negating options.

-nb: Number ifs and dos (Fortran).
----------------------------------

In the woven output, extra comments are added to help one correlate the block structure of the code.

-np: Print semicolons (Fortran).
--------------------------------

Although the Fortran input driver automatically terminates logical lines with semicolons so that the innards of FWEAVE can process them correctly, the semicolons are by default not printed.  To make them be printed, use the -np option.

-n\: Free-form syntax continued by backslash.
---------------------------------------------

In Fortran--90, this turns on free-form syntax and sets the continuation character to be the backslash.  For example,

     -n9[-n\]
     @
     @a
     program main;
     x = \
      y;
     end;

In the tangled output the backslash is converted into Fortran-90's standard continuation character, the ampersand.

-n&: Free-form syntax continued by ampersand.
---------------------------------------------

In Fortran--90, this turns on free-form syntax and sets the continuation character to be the backslash.  For example,

     -n9[-n\]
     @
     @a
     program main;
     x = &
      y;
     end;

-n/: Recognize short comments (Fortran).
----------------------------------------

The standard FWEB notation for a short comment is // ....  However, in Fortran the // denotes concatenation by default.  To make it denote a short comment, use the -n/ option.  For concatenation, use \/.

-n!: Make ! denote short comment (Fortran).
-------------------------------------------

-n): Reverse array indices (Fortran)
------------------------------------

This flag permits Fortran programmers to use C-style array indices. Conversions such as the following are made:

     a(k)(i) => a(i,k)
     a(k)(i,j) => a(i,j,k)
     a(k)(j)(i) => a(i,j,k)

This feature permits convenient definitions of macros to deal with multi-dimensional vectors.

-o: Don't overload operators.
-----------------------------

(To be finished.)

-q: Don't translate Ratfor.
---------------------------

(Obsolete.)

-P: Select TeX processor.
-------------------------

Say -PT or -PL to inform FWEAVE that its output will be processed by TeX or LaTeX, respectively.  If you always use LaTeX, it's easiest to put +PL into the .fweb initialization file.

-p: Buffer up a style-file entry.
---------------------------------

This option can be used in the .fweb initialization file to record style-file entries that are common to all runs.  This command buffers up the entries.  They are effectively placed at the beginning of the local style file, which is read after the command line is processed. See Style.

-r: Set global language to Ratfor--77.
--------------------------------------

See Languages, Ratfor.

-r9: Set global language to Ratfor--90.
---------------------------------------

See Languages, Ratfor.

-rg: Set goto parameters.
-------------------------

This obscure parameter is used for Ratfor (and really should be a style-file parameter).  Please see the manual.

-k: Suppress comments about Ratfor translation.
-----------------------------------------------

By default, the Ratfor translator writes comments about what command it is translating.  The -k option suppresses those comments.  Arguments to this command allows one to suppress comments about only particular commands; please see the reference guide.

-K: Write comments about Ratfor translation.
--------------------------------------------

This is the negative of -k; it forces comments about particular Ratfor commands.

-r;: Turn on auto-semi mode (Ratfor).
-------------------------------------

Please don't use this command.  Insert semicolons by hand in your Ratfor code.

-rb: Number ifs and dos (Ratfor).
---------------------------------

In the woven output, extra comments are added to help one correlate the block structure of the code.

-r/: Recognize short comments (Ratfor).
---------------------------------------

The standard FWEB notation for a short comment is // ....  However, in Ratfor the // denotes concatenation by default.  To make it denote a short comment, use the -r/ option.  For concatenation, use \/.

-r!: Make ! denote short comment (Ratfor).
------------------------------------------

-r): Reverse array indices (Ratfor)
-----------------------------------

-s: Print statistics.
---------------------

-s prints statistics about memory usage at the end of the run.

-sm prints statistics about memory usage at the end of the run, just as does -s; it also prints information about dynamic memory allocations as they occur.  -smnnn displays allocations of nnn bytes or more; if nnn is missing, 10000 is assumed.

-T: Flag-setting commands for FTANGLE.
--------------------------------------

This is a family of commands that set flags appropriate only for FTANGLE.

-TD: Permit processing of deferred macro definitions
....................................................

Deferred macro definitions are @m (or, equivalently, @#define) commands that appear in the code part rather than the usual definition part.  These definitions are evaluated during the output (phase 2), and can cause confusion when used with the preprocessor commands, which are evaluated during the input (phase 1). Because of this confusion, deferred macro definitions are prohibited by default.  To permit them, use the -TD option.

-Tv: Don't print header info
............................

By default, FTANGLE attempts to be helpful and prints some information about the command line, input and change files, etc. at the beginning of the output file.  This information can be deleted by means of the -Tv flag.  (This is done automatically when the -F flag is in effect, since the header information includes a time stamp that would defeat a successful file comparison.)

-T%: Don't retain trailing comments
...................................

Unless the -v option is used, comments are generally deleted by FTANGLE as it writes the output file.  However, in the TeX language such deletions can change the behavior of the output (by introducing extra spaces).  Therefore, for TeX comments that do not begin a line are always retained unless the -T% command is used. This command has no effect for languages other than TeX.

-t: Truncate identifiers.
-------------------------

The truncation option enables one to use a wider character set for identifiers than the language compiler will accept.  The standard example is vanilla-flavored Fortran, which doesn't allow the underscore. If one says `-tn6{_}', underscores will be removed from all identifiers, then the result will be truncated to length 6.  If the truncation procedure results in non-unique identifiers, these are listed.

-U: Convert reserved output tokens to lower case.
-------------------------------------------------

Particularly during RATFOR expansion, certain output tokens such as DO are produced in upper case.  The -U option forces such tokens to be produced in lower case.

-u: Undefine macro.
-------------------

-uA undefines the WEB macro previously defined on the command line (or in .fweb) via -m.

CAUTION:  This command can also undefine built-in functions such as $IF.  Don't do that, since built-ins can use other built-ins behind the scenes; undefining one can cause very strange behavior.

-v: Make all comments verbatim.
-------------------------------

By default, comments are not passed to the tangled output.  With -v, all comments are included verbatim in the tangled output.

-W: Flag-setting commands for FWEAVE.
-------------------------------------

This is a family of commands that set flags appropriate only for FWEAVE. Commands such as -W[ and -Wf can be combined as -W[f.

-W[: Process bracketed array indices
....................................

-Wdflmvw: Don't print various things in woven output
....................................................

The printing of selected definition-part commands can be suppressed as follows:

     -Wd --- outer definitions
     -Wf --- format statements
     -Wl --- limbo text definitions
     -Wm --- WEB macro definitions
     -Wv --- operator overloads
     -Ww --- identifier overloads

When these commands are used, associated cross-referencing is suppressed as well.

-w: Change name of macro package
--------------------------------

The command -w means ``Don't print \input fwebmac.sty as the first line of the .tex output file.''  The command -wfname means ``Print \input fname as the first line.''

-x: Reduce cross-reference information.
---------------------------------------

Cross-reference information (for FWEAVE) includes the table of contents ('c'), the index ('i'), and the module list ('m').  The command -x eliminates all of that information.  The command -xletters eliminates the piece of information corresponding to each letter in the list.  For example, -xim eliminates the index and the module list.

-X: Print selected cross-reference information.
-----------------------------------------------

This command is the opposite of -x.  See -x.

-y: Allocate dynamic memory.
----------------------------

This command changes the default size for a dynamically allocated memory buffer.  The buffers are indicated by a one- or two-character abbreviation such as "op".  The command -yop200 allocates 200 units for the "op" buffer.

To query the default allocations, just say -y.

For a more detailed discussion of memory allocation and a menu of the various dynamic arrays, see Memory allocation.

-Z: Display default style-file parameters.
------------------------------------------

The command -Zabc prints to the screen the default contents of the style-file parameters beginning with "abc".  Just -Z prints everything.

-z: Change name of style file.
------------------------------

The command -znew.sty changes the default style-file name fweb.sty to new.sty.  The command -z means ``Don't read any style file.''

Normally the style file is read from the same directory in which the WEB file resides.  To force fweb.sty to be read from the current directory, say -z..

-.: Don't recognize dot constants.
----------------------------------

If this command is used, the processors will not understand that constructions such as .LT. are operators in Fortran or Ratfor.  This command is useful if one is trying to modernize the source code to deal with symbols such as < instead of .LT..

-\: Explicitly escape continued strings.
----------------------------------------

(To be finished.)

-(: Continue parenthesized strings with backslashes.
----------------------------------------------------

-:: Set starting automatic statement number.
--------------------------------------------

Useful for Fortran and Ratfor.  Symbolic statement labels that are defined with the #:0 macro command are incremented starting with the default of 90000.  To change this to 789, say -:789.

->: Redirect output.
--------------------

This changes the name of the output file.  If no name is given, output is redirected to the terminal.

-=: Redirect output.
--------------------

Equivalent to ->.

-#: Turn off comments about line and module numbers.
----------------------------------------------------

By default, tangled output includes comments about the line and module numbers corresponding to the current piece of code.  To eliminate this clutter, say -#.

In some cases, bugs in tangled output, particularly Fortran, can be eliminated by using -#.  (But please report the bug anyway; Support.)

-+: Don't interpret compound assignment operators.
--------------------------------------------------

Both Ratfor and Fortran attempt to translate the commands ++, +=, --, -=, *=, and /= into code that behaves as its C counterpart.  To turn this feature off, use -+.

-/: Recognize short comments (Fortran & Ratfor).
------------------------------------------------

If this command is not used, the // construction will be interpreted as concatenation.

One way of invoking this option is with the global language command, such as @n/.  Another is to put the command into the initialization file .fweb.

-!: Make ! denote short comment (Fortran & Ratfor).
---------------------------------------------------

WEB COMMANDS
************

All WEB commands begin with the character @.  It is recommended that these begin in column 1 if possible.  This is required in some cases [e.g., the @x, @y, and @z in change files (see Change files), or column-oriented Fortran processing].

Some of these control codes may be used anywhere; others begin a new part.  For a quick summary of the control-code mappings and to see which codes begin new parts, use the -@ option.  See -AT.

Debugging commands
==================

Several commands provide localized versions of the -1 and -2 options related to debugging of pretty-printing.

@0: Turn off debugging
----------------------

This cancels the effect of a previous @1 or @2. See AT1, AT2.  The @0 command should appear in a different section from the @1 or @2 commands.

@1: Display irreducible scraps
------------------------------

@2: Display detailed reductions of the scraps
---------------------------------------------

Literal control characters
==========================

@@: The character @.
--------------------

@@ inserts the single character @.

Don't forget to double the @ even inside strings.  For example,

     puts("'@@' is represented by `@@@@'");

@|: Literal vertical bar, or optional line break.
-------------------------------------------------

In TeX mode, @| inserts a vertical bar.  This is useful inside LaTeX verbatim environments.  (A simple bar would signal a shift into code mode, which is probably not what you want.)

In code mode, @| inserts an optional line break in an expression.

Beginning of section
====================

@ : Begin minor section.
------------------------

@  begins a new minor (unstarred) section.  For example,

     @ This is an example of a minor section.  (No entry is made in the table
     of contents.)
     @a
     main()
     {}

@*, @*n: Begin major section.
-----------------------------

@* begins a new major (starred) section (of level 0).  The command must be followed by the name of the section (entry in the table of contents), followed by a period.

If @* is followed by a digit n, it begins a new major section of level n.  For example,

     @* MAIN PROGRAM.  This begins a major section (of level 0).
     @a
     main()
     {}

     @*1 Input routines.  Now follow some subroutines.
     @a
     get_input()
     {}

Beginning of code part
======================

The code part is begun by the appearance of either @a or @< Module name @>=.

@<: Begin module name.
----------------------

@< begins a module name, which has the form @< TeX text @>.  Module names inside WEB macro definitions begin with @#, not @<.

@>: End module name.
--------------------

@> ends a module name, of the form @< TeX text @>.

@A: Begin code part of unnamed section.
---------------------------------------

@A begins the code part of an unnamed section.  For example,

     @ In an unnamed section, the code part begins with @a.
     @a
     main()
     {}

@a: Begin code part of unnamed section, and mark.
-------------------------------------------------

@a begins the code part of an unnamed section (just as does @A), and in addition marks the next unreserved identifier it finds as defined in this section.  Precisely,

     @a == @A@[

Control codes b--z
==================

@b: Insert a breakpoint command.
--------------------------------

(To be finished.  Useful only for very intimate debugging of WEB codes.)

@c: Set language to C.
----------------------

See Languages, C.

@c++: Set language to C++.
--------------------------

See Languages, Cpp.

@D: Define outer macro.
-----------------------

This command begins the definition part.

@D defines an outer macro.  For more discussion, Outer macros. For example,

     @D A 1

@d: Define outer macro, and mark.
---------------------------------

This command begins the definition part.

@d defines an outer macro (just as @D does), and also marks the next identifiers as defined here.  It is equivalent to

@d == @D@[

@f: Format identifier or module name.
-------------------------------------

This command begins the definition part.

The construction

     @f identifier old_identifier

makes FWEAVE treat identifier like old_identifier.  For example,

     @f mytype int

says to treat the variable mytype just as int is treated (e.g., as a reserved word in C or C++).

The old_identifier may be one of the following special names, which insert extra spaces according to the positions of the underscores and behave as the part of speech indicated by the base names.  These are useful for dealing with macro constructions.

     $_BINOP_
     $_COMMA_
     $_EXPR
     $_EXPR_
     $EXPR_
     $UNOP_

When the current language is TeX, the format command can be used to change a category code according to the format

     @f `TeXchar new_cat_code

@i: Include file (unconditional).
---------------------------------

If one says

     @i test.hweb

the file test.hweb is inserted at the present point of the web file.  By default, the current directory is searched.  Files can be included from other directories by means of the FWEB_INCLUDES environment variable and/or the -I command-line option. See Environment variables, -I_.

@I: Include file (conditional).
-------------------------------

This commands behaves like @i if the command-line option -i is not used.  If it is used, then the contents of the included file is not printed in the woven output. See -i, -i!.

@L: Set language.
-----------------

@Ll sets the language to l, where l is one of {c,c++,n,n9,r,r9,x,v}. See Languages.

@l: Specify limbo text.
-----------------------

(This command begins the definition part.)

Limbo text is material that FWEAVE should output before the start of the first section.  For example,

     @l "\\def\\A{abc}"

Note that \\ stands for a backslash.  In general, characters must be escaped just as in C (so that one can include things like newlines in the definitions).

Limbo text may also be typed directly into the limbo section; in that case, no escapes are necessary since one is typing ordinary TeX text. Sometime, however, the @l command is useful for pedagogical purposes, as the limbo material can then be defined near the point where the logical discussion is made.

@M: Define WEB macro.
---------------------

This command begins the definition part.

For a detailed discussion of WEB macros, see Macros.

@m: Define WEB macro, and mark.
-------------------------------

This command begins the definition part.

For a detailed discussion of WEB macros, see Macros.

@N: Turn on N mode
------------------

This command must appear before the code part.

The N mode invokes language-independent behavior within the scope of a particular language.  The scoping rules are the same as for language changes; i.e., using @N within a given section produces language-independent behavior for that section and for any modules first referenced in that section.

Fundamentally, ``language-independent'' behavior essentially means a literal transcription of the input to the output.  For example, it inhibits blank compression by FTANGLE and tells FWEAVE to turn off ``pretty-printing'' (instead, the output is printed in typewriter type within a \begin{verbatim}...\end{verbatim} environment.

There are some subtleties with this mode (not to mention the likelihood of bugs):

 1. WEB macros and built-in functions will normally be expanded even in the N mode.  To inhibit expansion of a particular identifier, place @! before the identifier.  For example,

          @
          @m A 1
          @N
          @a
          @!A = A;

     expands to A = 1.

 2. Blank lines are significant.  The N mode is ended by the appearance of the @* or @  denoting the start of the next section.  If that were preceded by one or more blank lines, those would show up in both the tangled and woven output.  They might or might not be significant in the tangled output, but they almost certainly will look ugly in the woven output.  To avoid this, use the command @%%, which deletes the remainder of the current line and all immediately following empty lines.  For example,

          @
          @N
          @a
          x;@%%

          @ Next section.

 3. If the N mode is invoked from a compiler-like language such as Fortran, cross-referencing of variables is done as usual.  However, if the language is VERBATIM (which turns on the N mode automatically), no cross-referencing is done.  (Identifiers are still recognized according to FWEB's rules.  Those rules as currently implemented may be essentially meaningless for some languages; in the future, provision may be made for generalizing these rules by the user.)  To force an identifier to be placed into the index, precede it by @+.

@n: Set language to Fortran--77.
--------------------------------

See Languages.

@n9: Set language to Fortran--90.
---------------------------------

See Languages.

@O: Open output file (global scope).
------------------------------------

A statement of the form

     @O newfile.c

changes the name of the FTANGLE's output file.  This change remains in effect for the duration of the file, or until another @O is encountered.  (If that occurs, the previously open file is closed.)

This command is expanded during output, so it must appear in the code part.

@o: Open output file (local scope).
-----------------------------------

This behaves like @O, except the new file name is in effect only for the current section.

@r: Set language to Ratfor--77.
-------------------------------

See Languages.

@r9: Set language to Ratfor--90.
--------------------------------

See Languages.

@u: Undefine outer macro.
-------------------------

This command begins the definition part.

@u is the inverse of @d.  For example, in C it expands to #undef.

@v: Overload operator.
----------------------

This command begins the definition part.

For a detailed discussion of overloading operators, see Overloading.

@W: Overload identifier.
------------------------

This command begins the definition part.

For a detailed discussion of overloading identifiers, see Overloading.

@x: Terminate ignorable material, or begin material to be changed
-----------------------------------------------------------------

Please see the discussion of the @z command. See ATz.

@y: Begin change material
-------------------------

The @y command is permitted only in change files.  See Change files.

@z: Begin ignorable material, or terminate change
-------------------------------------------------

FWEB files may begin with the construction

     @z
     .
     .
     @x

where the @z and @x must begin in column 1. Material between the @z and @x is pure commentary and is ignored by both processors.

@z is also used in change files to end a change.  See Change files.

Conversion to ASCII
===================

Several commands are useful for generating machine-independent code. For example, FWEB works internally with the ASCII character set, so uses these commands heavily to convert from the possibly non-ASCII native character set of the machine on which FWEB is running.

@': Convert character to ASCII.
-------------------------------

The construction @'c' converts c to its ASCII value.  In C and C++, it is converted to octal; for example, @'A' is output as 0101. In Fortran and Ratfor, it is converted to decimal; the previous example would be output as 65.

If the native character set of your machine is ASCII, the conversion will not be done unless the -A command-line option is used. See -A_.

@": Convert string to ASCII.
----------------------------

The construction @"abc" converts the enclosed string to its ASCII representation.  For example, in C and C++ @"abc" will be output as "\141\142\143".

In Fortran and Ratfor, no such simple mechanism exists in the language, so a function call is issued.  For example, the previous example would be output as ASCIIstr('abc').  The user is responsible for defining the function ASCIIstr.  The name of this function can be changed by the style-file entry ASCII_fcn.  See ASCII_fcn.

If the native character set of your machine is ASCII, the conversion will not be done unless the -A command-line option is used. See -A_.

Forward referencing
===================

@[: Mark as defined.
--------------------

This command marks the next (non-reserved) identifier that appears after the @[ as being defined in the current section.  It is usually issued automatically; for example, @a is equivalent to @A@[.

Comments
========

@/*: Begin long verbatim comment.
---------------------------------

The following comment is copied to the tangled output.  If you desire all comments to be so copied, use -v.  See -v.

@//: Begin short verbatim comment.
----------------------------------

See the discussion of @/*, above.

@%: Ignorable comment.
----------------------

If any line in a web source code contains the command @%, all remaining material on that line (to and including the newline character) is ignored by the input driver and never processed at all.

A stronger form of this command is @%%.  This deletes the current line as well any empty lines that immediately follow.  This command is particularly useful when the N mode is in effect.  See ATN_.

@?: Begin compiler directive.
-----------------------------

The remainder of the line is processed as a compiler directive.  Optional material may be inserted automatically at the beginning of the tangled output line by means of the style-file option cdir_start. See Miscellaneous params.

@(: Begin meta-comment.
-----------------------

Material between @( and @) is treated in the N mode. For example,

     @(
     Comment 1
     Comment 2
     @)

Style-file parameters allow optional material to be insert at the beginning and end of the meta-comment, and at the beginning of each line of output.  For more information, see the style-file parameters beginning with meta (see Miscellaneous params).

@): End meta-comment.
---------------------

See the discussion of @(, ATlp.

Special brace
=============

@{: Suppress insertion of breakpoint command.
---------------------------------------------

This is for detailed debugging of FWEB codes.  It inserts a left brace and suppresses the insertion of a breakpoint command.  See ATb.

Index entries
=============

@_: Force index entry to be underlined.
---------------------------------------

This command applies to the next identifier that appears after the @_.  The index entry for that identifier will be underlined.

This command is usually issued automatically.  For example, the index entries for the variables i and j in the C statement int i,j; will be underlined.

@-: Delete index entry.
-----------------------

This command applies to the next identifier that appears after the @-; it prevents the index entry associated with that identifier from being underlined.  This might be useful when the N mode is in effect.

@+: Force index entry.
----------------------

This command applies to the next identifier that appears after the @+; it forces an index entry for that identifier. It is particularly useful when the language is VERBATIM, since cross-referencing is turned off in that case.

@^: Make index entry (Roman type).
----------------------------------

To insert one's own index entry in Roman type, say  @^My entry@>.

@.: Make index entry (typewriter type).
---------------------------------------

To insert one's own index entry in typewriter type, say  @^My entry@>.

@9: Make index entry (\9 format).
---------------------------------

The construction @9text@> is used to create an index entry in a format defined by the user.  It is associated with the macro \9, which would be called during TeX's processing of the index as \9{text}.  The user must define \9 according to the format

             \def\9#1{...}

Control text
============

@t: Put control text into a TeX \hbox.
--------------------------------------

Control text is material terminated by @>; it must be all on one line and must not contain any @s.  When FWEAVE sees the command @tcontroltext@>, it packages the control text into an \hbox and ships it to the output.  This command is ignored by FTANGLE.

@=: Pass control text verbatim to the output.
---------------------------------------------

For FTANGLE, the command @=controltext@> sends the control text to the output exactly as input.  (`Control text' is defined in the discussion of the @t command, ATt.) FWEAVE highlights the control text by drawing a box around it.

Spacing
=======

The spacing commands are used to refine FWEAVE's pretty-printed output.  Generally it's not necessary to bother with these until you're putting the final touches on a code.

@,: Insert a thin space.
------------------------

Extra spacings are sometimes necessary when working with unusual macro constructions.  (Need an example here.)

@/: Force a line break.
-----------------------

For example,

     int@/
       i,@/
       j,@/
       k;

@|: Literal vertical bar, or optional line break.
-------------------------------------------------

In TeX mode, @| inserts a vertical bar.  Here's a LaTeX example:

     \begin{verbatim}
       The constructions @|x@| and |x| are very different.
     \end{verbatim}

You might wish to try this out to see what FWEAVE produces.

In code mode, @| inserts an optional line break in an expression.

@#: Blank line.
---------------

@# forces a line break with some extra vertical white space.  Note that blank lines in the source are significant, so this command should seldom be necessary.

if @# is immediately followed by a letter, it is assumed that a preprocessor command is beginning.  See Preprocessing.

@~: Cancel line break.
----------------------

For example,

     printf("Working..."); @~ fflush(stdout);

@&: Join items.
---------------

During FWEAVE's output, @& joins the items to either side with no spaces or line breaks inbetween.

This command must be distinguished from the preprocessor construction ## (paste tokens together).  In a macro definition, a##bc creates the single identifier abc.  If one said a@&bc, two identifiers would be output with no spaces separating them.  In simple cases, the results may look identical, but consider how things would differ if abc were itself a WEB macro.

Pseudo (invisible) operators
============================

@e: Pseudo-expression.
----------------------

@e is an invisible expression.  See Pseudo-operators.

@;: Pseudo-semicolon.
---------------------

@; is an invisible semicolon.  These are often used in C programming to terminate a module name that expands to a compound statement.  For example,

     @c
     @a
     if(flag)
             @<Compound statement@>@;
     else
             @<Simple statement@>;

     @
     @<Com...@>=
     {
     x;
     y;
     }

     @
     @<Sim...@>=
     z

See Pseudo-operators.

@:: Pseudo-colon.
-----------------

@: is an invisible colon.  See Pseudo-operators. It can be helpful in formatting certain C constructions correctly.  For example,

     @<Cases@>=
     case 1:
     case 2:
     case 3@:

Miscellaneous commands
======================

@!: Inhibit macro expansion
---------------------------

FWEB macros and built-in functions are always expanded by default. This may not be desirable, particularly in the N mode.  To inhibit expansion of an individual identifier, preface it by @!.

COMMENTING STYLES
*****************

FWEB allows a variety of commenting styles. The visible comments are in the font \cmntfont, which defaults to \tenrm.

Invisible comments
==================

     @z...@x --- If a source or include file begins with @z, then all
                 material is skipped until and including a line beginning in
                 column 1 with @x.

     @%       --- All material until and including the next newline is
                 completely ignored.

     @%%      --- As @%, but also skip blank lines that immediately
                  follow the current line.

For example,

     @z
     Author:  J. A. Krommes
     @x
     @c @% This sets the global language to C.
     @* EXAMPLE.

Visible comments
================

/* ... */ is a long comment (may extend over several lines).

// ... is a short comment (terminated by next newline).

@(...@) is a meta-comment.  Meta-comments are a localized form of the N mode.  Tangled meta-comments are begun by the contents of the style-file entry meta.top and terminated by meta.bottom. Each line of the meta-comment is begun by meta.prefix.  Woven meta-comments are begun by meta_code.begin and ended by meta_code.end.  See Miscellaneous params.

     @n
     @a
             program main
     /* Get input. */
             call get_input // Read the parameter file.
     /* Process information.  Comments like this
        can be split over several lines. */
     @(
     Meta-comments provide a poor-man's alignment feature
      i --- counter
      x --- data value
     @)
             i = 1
             x = 2.0
             call exec(i,x)
             end

The use of meta-comments is not recommended.  Use ordinary long comments instead.  Inside of them, use the various powerful features of TeX or LaTeX (such as \halign) to format your comment appropriately.

MACROS and PREPROCESSING
************************

FWEB recognizes two kinds of macros:  outer macros, and WEB macros or inner macros.  Control codes associated with either of these kinds normally begin the definition part.  However, WEB macros are sometimes allowed in the code part as well; WEB macros.

Outer macros
============

Outer macros are defined by @d.  These may be placed in any definition part.  They are collected during phase 1; during phase 2, they are simply copied in order of their appearance to the beginning of the output file.  This is most useful for C or C++ codes; it's a shorthand way of typing #define when the positioning of the #define is unimportant.

As an example,

     @c
     @
     @d YES 1
     @d NO 0
     @a
     main()
     {}

     @
     @d BUF_LEN 100
     @a
     ...

The keyword into which the @d is translated is language-dependent; it is controlled by the style-file parameter outer_def. See Miscellaneous params.

Outer macros can be undefined by @u.  The translation is controlled by the style-file parameter outer_undef. See Miscellaneous params.

WEB macros
==========

WEB macros are defined by @m.  These should normally be placed in the definition section.  They are collected during FTANGLE's phase 1 and placed at the top of the unnamed section, so they are all known during the output in phase 2.

In unusual situations when macros are being conditionally defined and/or undefined, the order of processing a macro definition becomes significant.  If the command-line option -TD is used, then WEB macros may be used in the code part as well; they are then called deferred macros.  These definitions will be processed during phase 2 in the order that the code sections are processed, which may not be the same as the physical order in the source file.

WEB macros are often used in conjunction with the WEB preprocessor commands.  Preprocessor commands are always processed during phase 1, so they do not interact properly with deferred macros. It is for this reason that deferred macros are normally prohibited from appearing in the code part.

Various features of WEB macros
------------------------------

  * WEB macros with a variable number of arguments are indicated by an ellipsis, as in

          @m VAR(x,y,z,...) text

  * Adjacent strings in macro text are automatically concatenated.

Special tokens
--------------

The following special tokens may be used in the text of WEB macro definitions:

ANSI C-compatible tokens
........................

      ##          --- Paste tokens on either side to form a new identifier.
      #parameter  --- Convert parameter to string (without expansion).

Extensions to ANSI C macro syntax
.................................

(In the following list, the forms #{n} and #[n] may not work correctly in complicated situations.  This is a design deficiency that will be corrected someday.)

      #*parameter --- Like #parameter, but pass a quoted string through unchanged.
      #!parameter --- Don't expand argument.
      #'parameter --- Convert parameter to a single-quoted string (no expansion).
      #"parameter --- Convert parameter to a double-quoted string (no expansion).
      #0          --- Number of variable arguments.
      #n          --- n-th variable argument, counting from 1.
      #{0}        --- Like #0, but the argument may be a macro expression
                      known at run time.
      #{n}        --- Like #n, but the argument may be a macro expression.
      #[0]        --- The total number of arguments (fixed + variable).  (The
                      argument inside the brackets may be a macro expression.)
      #[n]        --- The n-th argument (including the fixed ones), counting
                      from 1.  (The argument inside teh brackets may be a
                      macro expressions.)
      #.          --- Comma-separated list of all variable arguments.
      #:0         --- Unique statement number (expanded in phase 1).
      #:nnn       --- Unique statement number for each invocation of this
                      macro (expanded in phase 2).
      #<          --- Begin a module name.
      #,          --- Internal comma; doesn't delimit macro argument.

Built-in functions
------------------

Built-in functions are essentially macros, but they sometimes implement functions that a user could not define.  They all begin with a dollar sign and are in upper case.

In the original FWEB design, built-in functions began with an underscore.  This usage conflicts with the conventions for reserved words in ANSI C.  In fact, FWEB understands built-in function names that begin with either a dollar sign or an underscore.  If you don't like the underscore convention for some name, you can undefine it, as in

     @#undef _A

No user-defined macro should begin with an underscore or a dollar sign!  It might interfere with the functioning of some internal built-in function.

$A: Convert to ASCII.
.....................

$A(string) is the built-in equivalent of @'...' or @"...".  (See ATquote and see AT".) Note the extra parentheses required by the built-in.

$ABS: Absolute value.
.....................

$ABS(expression) returns the absolute value of the macro expression.

$ASSERT: Assert a condition.
............................

$ASSERT(expression) evaluates the macro expression.  If the expression is false, an error message is printed and the run aborts.

This built-in is useful for ensuring that WEB macros required by the code are properly initialized.  It must appear in the code part (not the definition part).

$COMMENT: Generate a comment.
.............................

$COMMENT(string) generates a comment in the output file.

This built-in is sometimes useful in conjunction with the processing of WEB macros, since ordinary comments are removed when macros are processed.

$DATE: Today's date.
....................

$DATE generates a string consisting of the date in the form "August 16, 2001".

$DAY: The day.
..............

$DAY generates a string consisting of the day of the week, such as "Monday".

$DECR: Decrement a macro.
.........................

$DECR(N) redefines the numeric macro N to be one less than its previous value.  (If N does not simplify to a number, an error results.)  In other words, in the language of C the effect is to say N--.

The two-argument form $DECR(N,M) executes the equivalent of N -= m.

$DEFINE: Deferred macro definition.
...................................

$DEFINE (to be finished).

$DO: Macro do loop.
...................

$DO(macro,imin,imax[,di]){...} repetitively defines macro as would the FORTRAN statement do macro = imin,imax,di.  For example,

     $DO(I,0,2)
       {
       a[I] = I;
       }

generates the three statements

       a[0] = 0;
       a[1] = 1;
       a[2] = 2;

Do not assume that the macro remains defined after the end of the iteration.

Instead of the delimiting braces, parentheses may be used.  These may be useful to help FWEAVE format certain constructions correctly.

Nested delimiters are handled correctly.  The delimiters are required even only a single statement is to expanded.

$DUMPDEF: Dump macro definitions to the terminal.
.................................................

In the call $DUMPDEF(m1,m2,...), m1, m2, and so on are macro calls (with arguments if appropriate).  Two lines of output are generated for each argument.  Line 1 is the macro definition; line 2 is its expansion using the provided arguments.

You can use this built-in to debug your own macros, or to find out the secrets of FWEB's built-ins.

$E: Base of natural logarithms.
...............................

The expression $E returns E to the default machine precision. The expression $E(iprec) returns E to the decimal precision IPREC (which must be less than 50).

$ERROR: Send error message to output.
.....................................

$ERROR(string) prints an error message in FWEB's standard form.

$EVAL: Evaluate a macro expression.
...................................

$EVAL(expression) used FWEB's expression evaluator to reduce the macro expression to its simplest form.  An attempt to perform arithmetic on combinations of non-macro identifiers and numbers generates a warning message.

$EXP: Exponential function.
...........................

$EXP(x) returns E to the power X.

$GETENV: Get value of environment variable.
...........................................

$GETENV(name) returns a string consisting of the current value of the environment variable name.  (Under VMS, logical names behave like environment variables.)

$HOME: The user's home directory.
.................................

$HOME is equivalent to $GETENV(HOME).

$IF: Two-way conditional.
.........................

(To be finished.)

$IFCASE: n-way conditional.
...........................

$IFDEF: Two-way conditional.
............................

$IFNDEF: Two-way conditional.
.............................

$IFELSE: Two-way conditional.
.............................

$INCR: Increment a macro.
.........................

$INCR(N) redefines the numeric macro N to be one greater than its previous value.  (If N does not simplify to a number, an error results.)  In other words, in the language of C the effect is to say N++.

The two-argument form $INCR(N,M) executes the equivalent of N += m.

$INPUT_LINE: Line number that begins current section.
.....................................................

$INPUT_LINE is the number of the line in the WEB source file that begins the current section.

$L: Change to lower case.
.........................

$L(string) changes string to lower case.

$LANGUAGE: Identifier for current language.
...........................................

This expands to an identifier that denotes the current language, as follows:

     Language    $LANGUAGE
      C             $C
      C++           $CPP
      Fortran       $N
      Fortran-90    $N90
      Ratfor        $R
      Ratfor-90     $R90
      TeX           $X
      VERBATIM      $V

Note that these are identifiers, not WEB macros.  They are intended to be used in $IF or $IFELSE statements such as

     $IF($LANGUAGE==$C, C-text, other-text)

For multiway switches, the $LANGUAGE_NUM built-in is more useful; $LANGUAGE_NUM.

$LANGUAGE_NUM: Number of current language.
..........................................

$LANGUAGE_NUM expands to an integer that uniquely defines the current language, as follows:

     Language  $LANGUAGE_NUM
      C             0
      C++           1
      Fortran       2
      Fortran-90    3
      Ratfor        4
      Ratfor-90     5
      TeX           6
      VERBATIM      7

This built-in is useful in conjunction with an $IFCASE construction; $IFCASE.

$LEN: Length of string.
.......................

$LEN(string) returns the length of string in bytes.  If string is not surrounded by quotes, it is interpreted as if it were quoted (so it is not expanded if it is a macro).  Thus, in the example

     @m SS string
     $LEN(SS)

the value returned is 2, not 5.

$LOG: Natural logarithm.
........................

$LOG(x) returns the natural logarithm of X.

$LOG10: Logarithm to the base 10.
.................................

$LOG10(x) returns the logarithm to the base 10 of X.

$M: Define a macro.
...................

$M is equivalent to $DEFINE.  See $DEFINE.

$MAX: Maximum of a list.
........................

$MAX(x1,x2,...) returns the minimum of the list of arguments. (There must be at least one argument.)

(To be finished.)

$MIN: Minimum.
..............

$MIN(x1,x2,...) returns the minimum of the list of arguments. (There must be at least one argument.)

$MODULE_NAME: Name of present WEB module.
.........................................

$MODULES: Total number of independent modules.
..............................................

$MODULES gives the total number of independent modules---that is, the number of independent module names, plus 1 for the unnamed module.

$OUTPUT_LINE: Current line number of tangled output.
....................................................

$P: The C preprocessor symbol '#'.
..................................

$P is a synonym for $UNQUOTE("#").  See $UNQUOTE. It is useful for constructing WEB macro definitions that expand to C preprocessor statements.  For example,

     @m CHECK(flag)
             $P if(flag)
                     special code;
             $P endif

$PI: Pi.
........

The expression $PI returns PI to the default machine precision.  The expression $PI(iprec) returns PI to the decimal precision IPREC (which must be less than 50).

$POW: Exponentiation.
.....................

$POW(x,y) generates x raised to the power y.

$ROUTINE: Current function (RATFOR only).
.........................................

When RATFOR is the current language, $ROUTINE expands to a string built of the name of the current program, function, or subroutine.  This function is not useful for other languages, for which it expands to the null string.

$SECTION_NUM: Number of current WEB section.
............................................

$SECTION_NUM returns an integer greater than 0 that is the number of the current WEB section.  (This is not the LaTeX section number such as 3.4.)

$SECTIONS: Maximum section number.
..................................

$SECTIONS is the maximum section number as understood by FWEAVE.

$SQRT: Square root.
...................

$SQRT(x) return the square root of x.

$STRING: Expand, then stringize.
................................

$STRING(s) expands its argument if it is a macro, then makes the expansion into a quoted string.  If the argument is already a quoted string, it is returned unchanged.

$STUB:
......

(To be finished.)

$TIME: The time.
................

$TIME returns a string consisting of the local time in the form "19:59".

$TRANSLIT: Transliteration.
...........................

(To be finished.)

$U: Change to upper case.
.........................

$U(string) changes string to upper case.

$UNDEF: Undefine a macro.
.........................

$UNDEF(macro) undefines a WEB macro.

$UNQUOTE: Remove quotes from string.
....................................

$UNQUOTE(string) returns string without its surrounded quotes.

$VERBATIM: (Obsolete)
.....................

This was an old name for $UNQUOTE.  See $UNQUOTE.

$VERSION: Present FWEB version number.
......................................

$VERSION returns a string built out of the FWEB version number, such as "1.32".

Preprocessing
=============

FWEB preprocessor commands may appear in either the definition or the code parts.  But BEWARE:  No matter where they appear, they are expanded during INPUT, not output.  (This is probably a design flaw.)  For more discussion, WEB macros.

     @#define identifier --- Define a WEB macro; equivalent to @m.
     @#undef identifier  --- Undefine a WEB macro.

     @#ifdef identifier  --- Is WEB macro defined?  Equivalent to
                              @#if defined identifier.
     @#ifndef identifier --- Is WEB macro not defined?  Equivalent to
                              @#if !defined identifier.

     @#if expression
     @#elif expression
     @#else
     @#endif

In the @#if statement, the expression may contain WEB macros, but must ultimately evaluate to a number.  If that number is zero, the expression is false; otherwise, it is true.

The expression following constructions such as @#if is evaluated by a built-in expression evaluator that can also be used for other purposes, such as in macro expansion.  Its behavior is again motivated by expression evaluation in ANSI C; it is not quite as general, but should be more than adequate.  (One design flaw that will be fixed someday is that the order of expression evaluation is not necessarily left-to-right, as it is in C.) It supports both integer and floating-point arithmetic (with type promotion from integer to floating-point if necessary), and the ANSI defined operator. Operators with the highest precedence (see table below) are evaluated first; as usual, parentheses override the natural order of evaluation. The unary operator defined has the highest precedence; all the other unary operators have the next highest (and equal) precedence; then come the binary operators. When the operator exists in C, the action taken by FWEB is precisely that that the C compiler would take. Arithmetic is done in either long or double variables, as implemented by the C compiler that compiled FTANGLE.  (This was the easy choice, not necessarily the most desirable one.)

The operators, listed from  highest precedence  to lowest, are as follows (printed documentation only):

LANGUAGES
*********

FWEB has the ability to work with more than one language during a single run.  The language in effect at the beginning of the first section defines the global language.  Further language changes within a section have scope local to that section.

Usually, `language' means a compiler language like Fortran or C. These languages will be ``pretty-printed'' by FWEAVE. Pretty-printing can be inhibited by turning on the N mode (globally, with the command-line option -N; locally, with @N) or by selecting the VERBATIM `language'; in both of these cases, the input text is echoed literally to the output of both FTANGLE and FWEAVE.

`Language' is a stronger concept than `mode'.  For example, when a language is selected, the extension of the tangled output file is changed appropriately---for example, if test.web contains C code (that is, contains the command @c), test.web tangles into test.c (compressing blanks and otherwise making the tangled output relatively unreadable) and FWEAVE pretty-prints using the C syntax.  Turning on the N mode does not affect the language; FTANGLE copies the source code literally into test.c (no blank compression or other modifications), and FWEAVE typesets the source code within a verbatim environment (no pretty-printing).  When the VERBATIM language is selected, the N mode is turned on automatically, but FTANGLE writes its output to a file with a special default extension that can be customized in the style file. See Miscellaneous params.

Setting the language
====================

The most general form of a language command is

@[L]ltext[options]

where l is a language symbol, text is converted into a hyphenated option, and options have the same syntax as on the command line.  The language symbols must be in lower case; they are

     C          --- c
     C++        --- c++
     Fortran-77 --- n
     Fortran-90 --- n9
     Ratfor-77  --- r
     Ratfor-90  --- r9
     TeX        --- x
     VERBATIM   --- v

Thus, for example,

     @n9[-n&]

means set the language to Fortran--90 and use free-form syntax with the ampersand as the continuation character.

A language command should appear somewhere in limbo, before the start of the first section.  The language in effect at the beginning of the first section defines the global language.

Language commands may be used within sections, but the new language remains in force only for that section.  The language of a named module is inherited from the language in effect at the time the name is first used.  Thus, in the following example, the global language is Fortran--77, but an arbitrary number of C functions can be placed into a C-language module with just one @c language-changing command.

     @n
     @
     @a
             program main
             end

     @c
     @<C@>@;

     @
     @<C@>=
     int fcn()
     {}

FTANGLE will write two output files for this example.

Special hints and considerations for each language
==================================================

C
-

Special remarks.  (To be completed.)

C++
---

Special remarks.  (To be completed.)

Fortran
-------

Special remarks.  (To be completed.)

Ratfor
------

Special remarks.  (To be completed.)

TeX
---

Special remarks.  (To be completed.)

Verbatim
--------

Special remarks.

RATFOR
******

``Ratfor'' stands for ``RATional FORtran''.  More...

Ratfor commands
===============

Ratfor--77 commands
-------------------

      break;
      case i:
      default:
      do ...; {...}
      else {...}
      for(a;b;c) {...}
      if(condition) {...}
      next;
      repeat {...} until(condition);
      return expression;
      switch(expression) {...}
      while(condition) {...}

Additional Ratfor--90 commands
------------------------------

      contains:
      interface name {...}
      interface operator(op) {...}
      interface assignment(assgnmnt) {...}
      module name {...}
      private:
      sequence:
      type name {...}
      where(expression) {...}

Caviats about Ratfor
====================

The version of Ratfor built into FWEB differs slightly from its Unix counterpart:

 1. Numeric statement labels must be followed by a colon; they should be first on their line.

 2. The quoting convention for characters and strings follows that of C:  Single-quote single characters, double-quote strings.

 3. In a switch, cases fall through to the next case unless terminated by break (just as in C).

 4. The do statement must be terminated by a semicolon if followed by a simple statement.  (It's unnecessary if followed by a left brace that begins a compound statement.)

 5. Use && and || for the logical AND and OR.

 6. Do not use an end statement at the very end of a program unit; it is added automatically when the closing brace is sensed.

FORMATTING
**********

FWEB uses TeX to format its documentation.  Either Plain TeX or LaTeX may be used.  FWEB's ``new look'' beginning with Version 1.40 is very flexible, but works only with LaTeX.

Typesetting
===========

FWEAVE works in conjunction with either TeX or LaTeX.  It is always possible to create an adequately typeset document by processing with TeX. However, FWEB's ``new look'' (beginning with version 1.40) is designed to work with LaTeX; it probably will not be retrofitted to TeX unless days become longer than 24 hours.  The new look is more book-like, following ideas from Briggs' nuweb.

To inform FWEAVE you will be using TeX as the formatter, just say FWEAVE test or FWEAVE -PT test.  To inform it you will be using LaTeX, say FWEAVE -PL test.

If you will always be using a particular processor, you should probably put +PL into your .FWEB file (see Initialization).

FWEAVE's OUTPUT
---------------

When one says FWEAVE test, the file test.tex is created. The TeX commands contained in this file are organized into several sequential groups.

 1. \input command to read in FWEAVE's macro package.

     By default, the initial input command is \input fwebmac.sty.  The name of the macro package can be changed with the -w command-line option.  See -w.

 2. \Wbegin command (sets up the environment for TeX or LaTeX).

     The \Wbegin macro sets up certain defaults.  These can be overridden in the limbo section.

 3. Limbo text from the style-file parameter limbo.  See limbo.

 4. Beginning of user's limbo section.

 5. TeX commands for individual WEB sections.

 6. \input command to read in the index data file.

 7. \input command to read in the module-list data file.

 8. \Winfo command (summarizes some status information).

 9. \Wcon command (generates the table of contents, and ends the run).

LaTeX support
-------------

Original LaTeX support (through version 1.30) was substantially incomplete in that LaTeX's \output routine was usurped by the relatively simple one used for FWEB's TeX support.  However, beginning with version 1.40, full LaTeX support is provided.  LaTeX's \output routine is used, as are its sectioning commands (with minor changes), table-of-contents facilities, etc.

LaTeX's document style
......................

FWEAVE uses \documentstyle{article}.  The document style can be changed by the style-file option LaTeX.style.  See Fwebmac params. However, FWEAVE has not been tested with other document styles.

To incorporate style options---i.e., to obtain the effect of \documentstyle[myoptions]{article}, use the style-file option LaTeX.options, as in

     LaTeX.options "myoptions"

TeX commands in the user's limbo section will appear after the \documentstyle and \begin{document} commands, so may be used to redefine macro definitions in the style file.

Sections in LaTeX
.................

FWEB's sectioning commands (@*, @*n, and @ ) are converted into LaTeX's section commands such as \section (n=0), \subsection (n=1), and \subsubsection (n=2).  During LaTeX's processing of the tex file, it keeps track of the maximum depth achieved by @*n.  This number is written as the last item in the .aux file.  During the next LaTeX run, that number is used to map the @  commands to the next most insignificant sectioning command.  That level of sectioning command is slightly redefined from LaTeX's default, so don't try to redefine it.

The .aux file is also used by both processors to generate appropriate error messages that refer to the LaTeX section number instead of the internal one.

LaTeX's table of contents
.........................

In essence, the table of contents is produced by the LaTeX commands

     \pagenumbering{roman}
     \topofcontents
     \maketitle
     \tableofcontents
     \botofcontents
     \newpage

By default, the FWEB hooks \topofcontents and \botofcontents are empty, but they may be used in special circumstances to override the usual behavior.  One can set the parameters for \maketitle in the limbo section in the usual LaTeX way, except that one is encouraged to use FWEB's \Title macro instead of \title:

     \Title{MYCODE.WEB}
     \author{My name}
     \date{January 1, 2001}

By default, FWEAVE uses

     \title{}%
     \author{}%
     \date{\today\\[3pt]\Time}%

Customizing LaTeX's output
..........................

Several flags are provided to change the appearance of the final LaTeX document.  These are

  * \ifpagerefs (index references by pages or section numbers).

  * \numberTeX (number the beginning of the TeX part).

  * \numberdefs (number the beginning of the definition part).

  * \numbercode (number the beginning of the code part).

The defaults for these flags are

     \pagerefsfalse
     \numberTeXfalse
     \numberdefstrue
     \numbercodetrue

Page references
---------------

When one says \pagerefstrue (LaTeX only), index references are made by page numbers rather than module numbers or LaTeX section numbers.  If there is more than one section per page, they are identified by a, b, c, etc., such as section 17b.

The information necessary to process page references in this way is written into the .aux file.  As usual with LaTeX, several runs may be required for the references to be fully consistent with the source file.

(To be finished.)

Pretty-printing
===============

Pretty-printing refers to FWEAVE's attempt to typeset and highlight the code in a readable way.  This is usually done automatically for all of the compiler-like languages such as C. However, it can be inhibited by turning on the N mode with @N or by using the VERBATIM language (selected with @Lv).

(More...)

Pseudo-operators
----------------

Pseudo-operators behave like a particular part of speech for the purposes of FWEAVE's formatting, but are invisible on output.  The pseudo-operators are

     @e --- pseudo-expression.  See ATe.
     @; --- pseudo-semicolon.  See AT;.
     @: --- pseudo-colon.  See ATcolon.

Alternatives for various input tokens
-------------------------------------

FWEAVE translates various input constructions into allegedly more readable symbols---for example, in FORTRAN it translates .LT. into <. The printed documentation contains a table of what you can type on input, and what FWEAVE will output.

Overloading operators and identifiers
-------------------------------------

For special effects in the woven output, there are commands to help one change the appearance of operators and identifiers.

Overloading operators
.....................

A feature common to both C++ and FORTRAN--90 is operator overloading, the ability to extend or redefine the definition of an operator such as .FALSE. or =.  FORTRAN--90 even allows one to define new `dot' operators---for example, one might define the operator .IN. to test for inclusion in a set.  In a nontrivial extension of the original design, FWEAVE allows one to define how overloaded operators should appear on output. Indeed, this feature can be used even when the language does not permit overloading in order to customize the appearance of the woven output.

The @v control code is used to change the appearance of an operator. The format is

     @v new_operator_symbol_or_name "TeX material" old_operator

This means ``Display the new operator according to the TeX material, but treat it like the old operator---e.g., unary or binary---for formatting purposes.  The quoted TeX material is treated just like a C string, so for example if you want to include a backslash you must escape it with another backslash. For example, we can make an equals sign display on output as a large left arrow by saying

     @v = "\\Leftarrow" =

Two \Fortran\ examples are

     @v .FALSE. "\.{.FALSE.}" .FALSE.
     @v .IN. "\\in" +

This feature can go a long way toward enhancing readability of the woven output, particularly when operators are actually being overloaded.  It can also lead to arbitrarily bizarre output that no-one else will understand. As usual, restraint is advised.

Overloading identifiers
.......................

Although operator overloading is quite useful, it does not allow one to change the appearance of identifiers.  In its most general form, such a facility becomes quite complicated; one must endow FWEAVE with a macro-processing facility analogous to that of FTANGLE.  This has not been done yet (probably it will be someday).  In the meantime, one has the command @W, which provides a restricted form of such a facility.  This command, new with version~1.30, is experimental, and not firmly established.  Changes in usage and/or syntax may be made in future versions.

The most general form of the @W command is

     @W identifier "replacement text"

This means:  Replace any references to identifier in the woven output with the replacement text.

A more restrictive form is

     @W identifier \newmacro

which replaces references to identifier with a call to \newmacro.  (Note that there are no quotes in this form.)

The shortest form is

     @W identifier .

which replaces references to identifier with a call to \identifier.  For example, the identifier x normally appears in woven output as \.{\Wshort\{x\}}.  If one says

     @W x .

one will instead get the macro reference \x, which could be defined to give a variety of special effects.

One of the important uses of this facility is to expedite special formatting of array references.  This subject is discussed separately below in the section on ``Special array formatting,'' where an example is given.

Information options
-------------------

Several of the command-line options can be used to elicit information about the initial state of FWEB.

-@ displays information about the control codes. See -AT.

-D displays information about reserved words.  See -D_.

-y displays default dynamic memory allocations.  See -y.

-Z displays default values of style-file parameters.  See -Z_.

CUSTOMIZATION
*************

The default behavior of FWEB can be changed in a variety of ways.

 1. Unix environment variables (logical variables in VMS) affect path or file names.

 2. An initialization file resides in the home directory.

 3. A style file resides in the current directory.

The initialization file (usually called .fweb) is intended to contain command-line options (one per line) that are to be used in every run.

The style file is intended to provide more local customization, perhaps differing for each run.  The style file does not contain command-line options; rather, it contains parameter settings that override FWEB's defaults.  The -p option (see -p) provides a means of incorporating style-file entries into .fweb.

The order of processing is:

 1. Evaluate environment variables.

 2. Read .fweb.

 3. Process .fweb options beginning with +.

 4. Read and process command-line options (except for -p).

 5. Process remaining .fweb options.

 6. Process any -p options.

 7. Read and process the style file.

Environment variables
=====================

FWEB_INCLUDES --- Colon-delimited list of directories to search for include files.  (One can append to this list by means of the -I option; see -I_.)

FWEB_INI --- Name of the initialization file. If not defined, either .fweb or fweb.ini is chosen, depending on the machine.  The initialization file always resides in $HOME.

FWEB_STYLE_DIR --- Directory in which style file resides.  If not defined, the current directory is used.

Initialization
==============

The initialization file
-----------------------

On startup, FWEB attempts to read an initialization file.  This always resides in the user's HOME directory.  It is usually called .fweb (fweb.ini on personal computers).  The default file name can be overridden by the environment variable FWEB_INI.

One may put into .fweb any option that might be used as a command-line option.  (Presently, there must be just one entry per line.)  If the option begins with a +, it is processed before the actual command-line options; otherwise, it is processed after.  Generally, .fweb options should begin with + so that one may override them from the command line.

Memory allocation
-----------------

The command-line option -y (see -y) is used to change the default allocation for a dynamic array.  The arrays have a one- or two-character abbreviation denoted by aa.  Some error messages will use this abbreviation when suggesting that you increase a default allocation.  To query the present allocations of variable aa, just say -yaa.  To query everything, say -y.

(The detailed explanations for these arrays aren't here yet.  The on-line info has a terse list.)

The Style file
==============

A style file (default name fweb.sty) may reside in the user's current directory (or directory specified by the environment variable FWEB_STYLE_DIR).  The default name can be changed by the command-line option -z (see -z).

The style file is processed after all command-line options have been processed.  Note that the command-line option -p (see -p) buffers up style-file entries.  Effectively, these are treated as residing in a temporary file that is read just before the local style file.  Thus, -p options placed in .fweb behave as `global' style-file entries and will be overridden by a matching entry in the local style file.

Style-file entries have the form

             keyword [=] value

For example,

             LaTeX.options = "eqalign"

The syntax is completely free-form.

The descriptions of the parameters aren't completed yet.  Please see the reference guide.

Customizing FWEAVE's index
--------------------------

index
.....

index.tex is the name of the file into which the index is written.  The character '#' is translated into the root name of the web file.

index.preamble are TeX commands that begin the index.

index.postamble are TeX commands that end the index.

index.collate specifies the collating sequence for the index.

delim
.....

delim_0 is the string to insert after the identifier in an index entry.

delim_n is the string to insert between two section numbers in an index entry.

group_skip
..........

group_skip is a string of TeX commands to insert between letter groups.

item_0
......

item_0 is the TeX command to begin an index entry.

language
........

language.prefix begins a language entry.; language.suffix ends one.

lethead
.......

lethead.prefix begins a letter group; lethead.suffix ends one.  The flag lethead.flag controls the format of the letter group: if it is zero, nothing is inserted; if it is positive, an upper-case letter is inserted; if it is negative, a lower-case letter is inserted.

underline
.........

underline.prefix is the TeX command to begin an underlined index entry.

underline.suffix is the TeX command to end an underlined index entry.

Customizing the module list
---------------------------

modules.tex is the name of the file into which the module names are written.

modules.preamble is a string of TeX commands to begin the list of modules.

modules.postamble is a string of TeX commands to end the list of modules.

modules.info is the name of the TeX macro that formats the command line and related information.

Customizing the table of contents
---------------------------------

contents.tex is the name of the file into which the table of contents is written.

contents.preamble is the TeX string that begins printing the table of contents.

contents.postamble is the TeX string that ends the table of contents.

Customizing cross-reference subscripts
--------------------------------------

When FWEAVE pretty-prints code, it can attach cross-reference subscripts to various kinds of identifiers.  The following flags select which identifiers are so subscripted.

Customizing the behavior of fwebmac.sty macros
----------------------------------------------

To some extent, the behavior of FWEB's macro package fwebmac.sty can be changed by means of the following parameters, instead of actually editing fwebmac.web itself.

format
......

The format fields specify the macro to use to pretty-print various kinds of identifiers, as follows: (not finished).

indent
......

indent.TeX specifies paragraph indentation for the TeX part.

indent.code specifies similar indentation for the code part.

When running under LaTeX, the documents is (effectively) begun by the command \documentstyle[options]{style}.  The options field can be specified by LaTeX.options; the style field by LaTeX.style.

(To be finished.)

Miscellaneous style-file parameters
-----------------------------------

ASCII_Fcn
.........

See AT".

cchar
.....

Continuation character for Fortran code output.

cdir_start
..........

This parameter has the form cdir_start.l, where l is one of C, Cpp, N, N90, R, R90, X, or V.  The contents of this parameter is written immediately after the @? that begins a compiler directive.

meta (FTANGLE)
..............

meta.top.l specifies text that precedes material enclosed by @(...@).

meta.prefix.l begins each line of the meta-comment.

meta.bottom.l specifies text that follows the meta-comment.

outer
.....

FTANGLE converts @d to outer.def, and @u to outer.undef.

protect
.......

The strings protect.l specify the protection character(s) to end a continued line.

suffix
......

The extension for the files output by FTANGLE is specified by suffix.l.

macros
......

The default name of the macro package to be read in.  (This can be overridden by the command-line option -w; see -w.)

limbo
.....

TeX material to be printed at the beginning of the limbo part, just before the text from @l commands.  See ATl.

meta (FWEAVE)
.............

preamble
........

Additional TeX material can be inserted at the beginning of a named section with preamble.named and at the beginning of an unnamed one with preamble.unnamed.

dot_constant
............

In Fortran, `dot' constants such as .LT. are begun and ended by periods.  In special circumstances, the beginning and ending characters may be modified by dot_constant.begin.l and dot_constant.end.l.

null_file
.........

The name of the null file.  For more discussion, see Change files.

Automatic file name completion:
-------------------------------

For more information, see -e.

USAGE TIPS and SUGGESTIONS
**************************

In this section we collect various tips and suggestions to help one make full use of FWEB.  (There's more to come here!)

Converting an existing code to FWEB
===================================

In summary, to convert an existing code to FWEB, you should do the following. (The following simple procedure assumes that you put all the subroutines into the unnamed module. However, other more elaborate schemes are possible.)

 1. Place invisible commentary about the author, version, etc. at the beginning of the source file by bracketing it with @z...@x.  The @z must be the first two characters of the file.

 2. Next, set the language by including a command such as @n.

 3. Place an @a command before each program unit (e.g., main program, subroutine, or function).

 4. Before each @a, place an @* or @  command, followed by TeX documentation about that particular section of code.

 5. If you have program units longer than about twelve lines, either make them function calls, if you can afford the overhead and can impart sufficient information via the function name, or break them up into shorter fragments by using named modules. Insert the command @<Name of module@> in place of the fragment you're replacing, then put that fragment somewhere else, prefaced by @  and @<Name of module@>=.

 6. Make sure your comments are valid TeX. (You can't have things like raw underscores or dollar signs in comments, since those cause TeX to take special actions.)

 7. Beautify and clarify your documentation by using code mode (enclosing stuff between vertical bars) liberally within your TeX.

 8. After you've seen the woven output, you may need to go back and format a few identifiers or section names so that FWEAVE understands them properly, or you may need to insert some pseudo-semicolons (@;), pseudo-expressions (@i), or pseudo-colons (@:).

 9. Consider using the built-in macro preprocessor to make your code more readable---for example, replace raw numerical constants by symbolic names.

 10. If you are a FORTRAN user,  for ultimate readability consider converting to RATFOR. The initial annoyance is getting rid of column~6 continuations. With the aid of a good editor, this can be done simply. For example, in emacs one can replace the regular expression [carriage return, five spaces, something not equal to space, tab, or 0] with [backslash, carriage return, six spaces]:

          M-x replace-regexp RET
          C-q C-j \.{\ \ \ \ \ }[\^\.\ tab 0]RET
          \\\\ C-q C-j \.{\ \ \ \ \ \ }RET

     Get rid of the keywords such as then or end if in favor of braces. Change singly-quoted character strings to doubly-quoted ones.

Programming tips and other suggestions
======================================

This section will be enlarged in the future!  Meanwhile, please feel free to contact krommes@princeton.edu for help and advice, and to suggest items to include here.

 1. Periodically check ftp.pppl.gov:/pub/fweb/READ_ME for bug reports and other news.  Make bug reports!  See Support.

 2. Most options in .fweb should begin with + so they can be overridden by command-line options for the job itself. See Initialization

 3. Put standard command-line options into .fweb.  Also put there standard style parameters---e.g.,

          +pindex.tex "#.ndx"
          +pmodules.tex "#.mds"
          +pcontents.tex "#.cts"

 4. Learn how to use the style file. See Style.

 5. Use the info options -@, -D, -y, and -Z to find out about various internal FWEB tables (control codes, reserved words, memory allocations, and style-file parameters). See Info options.

 6. Begin all FWEB sources with invisible commentary bracketed by @z...@x. See ATz.

 7. Always include an explicit language-setting command in the limbo section. See Languages.

 8. Keep sections quite short. Knuth suggests a dozen lines.  That's quite hard to achieve sometimes, but almost never should a section be more than a page long.

 9. It's easy to define macros from the command line to expedite conditional preprocessing. See -m.

 10. Use the preprocessor construction @#if 0...@#endif to comment out unwanted code. See Preprocessing.

 11. For logical operations with the preprocessor, use ||, not |.

 12. It's conventional to identify the ends of long preprocessor constructions as follows:

          @#if A
          .
          .
          @#endif // |A|

 13. To debug an errant WEB macro, use the built-in function $DUMPDEF. See $DUMPDEF.

 14. Use @? for compiler directives.  See AT?. Use the style-file parameters cdir_start to specify information that will be written out at the beginning of the line.

 15. Stick to the standard FWEB commenting style /*...*/ or //....  Don't use alternatives such as FORTRAN's column 1 convention; these may not work or may not be supported someday. See Comments.

 16. The meta-comment feature @(...@) provides a poor-man's alignment feature.  But that's not in the spirit of TeX; learn to use \halign or the LaTeX alternatives.

 17. In FORTRAN, use #:0 to declare readable alphabetic statement labels. See Macros

 18. When mixing languages, define the language of a module at the highest possible level---e.g., in the unamed module, not after @<...@>=.

NEW FEATURES, version 1.40
**************************

 1. The meaning of @+ has changed.  (SORRY!)  Formerly, this inhibited a line break; that function is now performed by @~. The new meaning of @+ is to force an index entry (the opposite of @-, which inhibits an index entry).

     If you have large codes using the old @+ that you do not wish to convert, you can recover the old mappings by placing the following commands into fweb.sty:

          yes_index = "~"
          no_line_break = "+"

     However, please try to make the conversion; the new codes are intended to be more symmetrical and easier to remember.

 2. Built-in functions now begin with $, not _.  The underscore prefix was a bad design decision; it introduces conflicts with ANSI C in certain circumstances.  To ease conversion, the old forms are still understood.  Thus, one can use $EVAL and _EVAL interchangably.  However, the underscore forms may be deleted in future releases.

 3. Full LaTeX support.  FWEB no longer usurps LaTeX's \output routine, and LaTeX's sectioning commands, table-of-contents commands, etc. are used.  The appearance of the woven output is changed to be more book-like.  (This is an experiment.)

 4. Verbatim language.  @Lv selects a language-independent format. See Verbatim

 5. Language-independent mode.  The N mode inhibits pretty-printing, blank compression, etc.; source code is essentially copied literally from input to output.  This mode is turned on automatically by the VERBATIM language, but it can also be used with the other languages.  It is turned on by the command-line option -N or the local command @N. See ATN_.

 6. Writing of temporary files.  When the -F command-line option is in effect, tangled output is written to temporary files instead of the final target files, and the temporary files are compared to the last version of the target files on disk.  If there is no change, the target files are not updated.  This avoid unnecessary recompilation if only the documentation, not the code, was changed.  See -F_.

 7. Converting output tokens to lower case.  See -U_.

 8. The built-in functions $E and $PI.  See $E, $PI.

 9. The built-in functions $EXP, $LOG, and $LOG10.  See $EXP, $LOG, and $LOG10.

 10. $MAX and $MIN generalized to take arbitrary list of arguments.  See $MAX, $MIN.

 11. The marriage-saver option.  In response to a serious user request, see -B_.

SUPPORT
*******

FWEB is supported by John Krommes, krommes@princeton.edu. This project is a spare-time activity!  I try for, but cannot promise, reasonably quick (one week) response to questions.  Bug reports submitted with very short test files will be verified.  For very simple fixes, a change file will be provided.  Generally, however, bugs are not fixed until the next release.  Releases occur intermittently, depending on my other professional obligations.

Suggestions are very welcome.  Many of FWEB's current features were incorporated in response to users' requests.  However, the queue for future improvements is long; nothing may happen immediately.

Marcus Speh moderates an FWEB FAQ.  See /pub/fweb/faq.

Index
*****

The index is obviously not complete; the following are tests.